Deploy preview for react-redux-docs ready!

Built with commit 8efcb26

https://deploy-preview-1106--react-redux-docs.netlify.com

Sweet! I'll try to take a look at this over the weekend.

Docusaurus's versioned docs feature does not assume versioned code. We don't need to keep the code branches of older versions.

Can it? We have a 5.x branch that we'll keep around for a bit while folks migrate to 6.0. If we can isolate doc versions by branches, that would actually be ideal.

Oh hey, you did cut a 5.x branch. I wasn't sure that we had one.

Per your question: no, I don't think that's how Docusaurus handles things. There's one published site, built from the current Markdown docs files. Older versions of the docs are, I believe, pre-generated HTML files that have been committed (?). But all that has to be on the same branch together, so that it can be copied to the docs build output folder.

Is there a chance to run some script pre-build that essentially does git --work-tree=website/versioned_docs/version-5.1.1/ checkout 5.x -- docs/?

Technically? Probably. But that's really not how DS is meant to work as far as I know, and I don't think it gains us anything useful.

I think Docusaurus' idea is that it assumes master branch is always next. And whenever we run docusaurus-version vx.x, it creates a directory for that version, and generates docs for that version based off the difference between that version and the latest version prior to that.

Only files in the docs directory and sidebar files that differ from those of the latest version will get copied each time a new version is specified. If there is no change across versions, Docusaurus will use the file from the latest version with that file.

In our case latest version was 5.1.1. master was 6.0, which was also @next. Once I ran docusaurus-version 6.0.0, it copied the docs from master that was different from 5.1.1. to versioned_docs/version-6.0.0. I changed api.md regarding forwardRef and passing store. Therefore only api.md was copied.

But all that has to be on the same branch together

Yeah I believe so. The generated versioned docs are under the doc site's directory.

Technically? Probably. But that's really not how DS is meant to work as far as I know, and I don't think it gains us anything useful.

I guess nothing would stop us from writing such script by ourselves. We just need to copy over the docs/ and the versioned_sidebars. The header and footer can be a bit off if they're not consistent across versions. And yeah, probably not how Docusaurus is designed to work.

Thanks for the explanation. In that case, since versioned docs do matter for this project (not so much with Redux, though), I think this looks good.

Mark, did you have any further tweaks to make to the base docs before we split out the versions?

Yeah, gimme another day or two to finish polishing things.

Any chance we can still get to this? With 7.0 imminent, it's going to be more important.

I believe so. I'll spend some time this weekend to catch up a bit, update this branch and let's see.

Hi @timdorr, @markerikson,

I've updated this branch and have put v5 to previous version, v6 to stable version, and put up a link to v7 as pre-release version. It should now work under Netlify's preview.

Changes

• Make version docs work: There's a doc number next to the logo, clicking on it will go to the versioned docs page
• Older versions are now v5.x, v6.x
  • v5.x: docs before v6 released
  • v6.x: docs of current master
• Put up a link to v7.x in the versioned docs page, this points to version "next" of the docs, which is the current master

Versioned docs structure

.
├──  # ... other files
├── docs                      # pre-release version (v7)
│   ├── README.md
│   ├── api
│   ├── introduction
│   ├── troubleshooting.md
│   └── using-react-redux
└── website
    ├── # ... other files
    ├── siteConfig.js
    ├── versioned_docs        # contains stable + previous versions
    │   ├── version-5.x       # copies docs/ when running docusaurus' version command
    │   └── version-6.x
    ├── versioned_sidebars 
    │   ├── version-5.x-sidebars.json
    │   └── version-6.x-sidebars.json
    ├── versions.json         # list of versioned files
    └── yarn.lock

Working with versioned docs

• To update docs for pre-release versions (v7), update the docs under root /docs.
• To update docs for any stable or previous versions, update the docs under /website/versioned_docs/
• Once pre-release version releases, run Docusaurus command yarn run version v7.x under /website, and remove nextVersion: 'v7.x' from website/siteConfig.js.

Oh, this is so good! Thank you!

@markerikson Any objections? I'd say just merge this in right now.

Sure, let's do it! @wgao19 , this is great - thanks!